kernel: msgq: adding support for `k_msgq_put_front` and sample code #92865

alexpaschoaletto · 2025-07-08T21:50:22Z

Following the examples of FreeRTOS and RTEMS, this PR introduces a k_msgq_put_front API for sending messages to the head of the queue, in a LIFO scheme. It also adds a simple sample code that demonstrates how it works.

Due to the fact that both versions of k_msgq_put share most of the code, this contribution creates an internal put_msg_in_queue function which inserts the message at the front or back of the queue depending on the flag put_at_back passed to it. Now the implementation looks like this:

/* internal function */
int put_msg_in_queue(struct k_msgq *msgq, const void *data, k_timeout_t timeout, bool put_at_back)
{
        /*
            puts message to front or back of the queue
            depending on the value or put_at_back
        */
}

int z_impl_k_msgq_put(struct k_msgq *msgq, const void *data, k_timeout_t timeout)
{
	return put_msg_in_queue(msgq, data, timeout, true);
}

int z_impl_k_msgq_put_front(struct k_msgq *msgq, const void *data, k_timeout_t timeout)
{
	return put_msg_in_queue(msgq, data, timeout, false);
}

note: some work concerning mainly docs and ci/cd still needs updating, but the bulk of the contribution is here. I'd like to have some opinions on this contribution before taking the time to do everyhing properly.

Closes #46339

andyross

A design nitpick around the cut/paste feel of the change.

Also: please isolate changes to the sample to a separate commit from the semantic change in the kernel.

And while a sample can be used as a test case, it's really best to put an actual test case of this functionality into tests/kernel/msgq/msgq_api

andyross · 2025-07-09T00:43:10Z

kernel/msg_q.c

+
+			/* give message to waiting thread */
+			(void)memcpy(pending_thread->base.swap_data, data,
+			       msgq->msg_size);


Not loving the duplication of the implementation code. Ideally all this should be shared. In particular maintenance-quality-issues are at their most important in code surrounding memory copies into/out-of caller pointers (which can cross security boundaries if CONFIG_USERSPACE=y!). Might take some refactoring to make that happen, obviously.

I understand and agree, but at first I really didn't want to touch in the already existing k_msgq_put function. So should I do something like this, then?

int _copy_to_queue ( ... , bool should_copy_to_back) { // shared implementation goes here } int z_impl_k_msgq_put( ... ) { return _copy_to_queue( ... , true); } int z_impl_k_msgq_put_urgent( ... ) { return _copy_to_queue( ..., , false); }

FWIW I have done just that to avoid code duplication.

andyross · 2025-07-09T00:46:26Z

samples/basic/msg_queue/src/main.c

+	}
+
+	received[BUF_SIZE - 1] = '\0';
+	/* we expect to see CBA012345... */


While this is a good note for understanding, it would be even better for this to be a test that actually checked messages were received in the expected order.

I agree. For now I have refactored the sample code to have a regex to check the sample output (with the message sequence) on the tests. I intend to do the proper ZTEST thing as you suggested as well, but I'd like to settle on the implementation before that.

TaiJuWu

Please add reference: #46339 to PR description.
Also this feature is good to be optional and it need more test.

TaiJuWu · 2025-07-09T02:17:37Z

kernel/msg_q.c

+		/* message queue isn't full */
+		pending_thread = z_unpend_first_thread(&msgq->wait_q);
+		if (unlikely(pending_thread != NULL)) {
+			SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_msgq, put, msgq, timeout, 0);


Add an additional trace log to facilitate easier debugging.

I like this idea, however I'm not certain on how to refactor this part. would this be just changing put by put_urgent (or whatever naming convention we end up deciding)? Like this:

SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_msgq, put_urgent, msgq, timeout, 0);

You can refer #71195
I think I finished most implements at that time.

kernel/msg_q.c

alexpaschoaletto · 2025-07-09T21:52:20Z

Please add reference: #46339 to PR description. Also this feature is good to be optional and it need more test.

done! not sure what you mean by "good to be optional", though. Proper tests will be done soon - I wanted some feedback on this contribution before taking the effort (if for some reason this was immediately discarded by reviewers, then it would be a waste of energy).

TaiJuWu · 2025-07-10T05:03:45Z

Please add reference: #46339 to PR description. Also this feature is good to be optional and it need more test.

done! not sure what you mean by "good to be optional", though. Proper tests will be done soon - I wanted some feedback on this contribution before taking the effort (if for some reason this was immediately discarded by reviewers, then it would be a waste of energy).

In my mind, the feature is not required for every developer so we can be optional and make the user to decide enabling it or not, this can reduce code size.

peter-mitsis · 2025-07-15T15:45:58Z

In my mind, the feature is not required for every developer so we can be optional and make the user to decide enabling it or not, this can reduce code size.

@TaiJuWu - I may be misunderstanding the intent behind your desire to make it optional for as I see it, it would in a sense automatically be so. That is, Zephyr uses garbage collection at build time to remove both unused functions and unused variables. Consequently, if no one uses the new urgent/front routine, it does not find its way into the final image.

peter-mitsis · 2025-07-15T16:02:36Z

kernel/msg_q.c

+				 * writing a message to the head of the queue is
+				 * less obvious, but it can be achieved by simply
+				 * following these steps:
+				 *
+				 * 1. decrementing the read pointer. This effectively
+				 * opens space for the incoming message in the head of
+				 * the queue.
+				 *
+				 * 2. temporarily matching the write pointer with the
+				 * read pointer. This way the message will be written
+				 * in the recently opened space.
+				 *
+				 * 3. reverting the write pointer after the write to its
+				 * original value. The read pointer, by its turn, should
+				 * be always at the head, so it doesn't need reverting
+				 * because we just wrote to the head.
+				 *
+				 * ...but this is inefficient because we need to go back
+				 * and forth with the value of write_ptr; note that it
+				 * becomes equal to read_ptr just to be restored afterwards.
+				 * A much more efficient solution is to simply write the
+				 * message directly to read_ptr's address after step 1,
+				 * which avoids needing to perform steps 2 and 3 altogether.


Let's simplify this comment. Perhaps something like ...

* writing a message to the front of the queue is * simple and effective: create space for the message * by decrementing read_ptr, then copy the message * to the newly created space

alright, I have reduced the message. I still think the full rationale is valuable, though.

peter-mitsis · 2025-07-15T16:08:21Z

kernel/msg_q.c

+	K_OOPS(K_SYSCALL_MEMORY_READ(data, msgq->msg_size));
+
+	return z_impl_k_msgq_put_front(msgq, data, timeout);
+}


I think we are missing ...

#include <zephyr/syscalls/k_msgq_put_front_mrsh.c>

really? ok, but what's that for?

It's part of the system call infrastructure--for marshalling function.

peter-mitsis · 2025-07-15T16:12:35Z

include/zephyr/kernel.h

+ *
+ * This routine sends a message to the beginning (head) of message queue @a q.
+ * Messages sent with this method will be retrieved before any pre-existing
+ * messages in the queue.


Thanks for adding the note. I still think that it is important to have in there.

peter-mitsis · 2025-07-15T16:15:06Z

include/zephyr/kernel.h

@@ -4785,7 +4785,7 @@ __syscall int k_msgq_alloc_init(struct k_msgq *msgq, size_t msg_size,
 int k_msgq_cleanup(struct k_msgq *msgq);

 /**
- * @brief Send a message to a message queue.
+ * @brief Send a message to the end of a message queue.


The commit message still has a referent to k_msgq_put_urgent instead of k_msgq_put_front.

thanks for the notice, changed it already.

TaiJuWu · 2025-07-15T16:35:50Z

In my mind, the feature is not required for every developer so we can be optional and make the user to decide enabling it or not, this can reduce code size.

@TaiJuWu - I may be misunderstanding the intent behind your desire to make it optional for as I see it, it would in a sense automatically be so. That is, Zephyr uses garbage collection at build time to remove both unused functions and unused variables. Consequently, if no one uses the new urgent/front routine, it does not find its way into the final image.

Thanks for your explanation, I have not known this knowledge, I agree with you.

TaiJuWu · 2025-07-16T13:52:02Z

samples/kernel/msg_queue/README.rst

+
+   [producer] sending: 0
+   [producer] sending: 1
+   [producer] sending: A (urgent)


urgent or front?

in the context of the sample, the publisher thread sends normal and urgent messages. It's not related to the API naming.

Got it, thanks.

peter-mitsis · 2025-07-16T16:46:53Z

Once the minor compliance check is fixed, I expect I will be giving this a +1.

JarmouniA

Mostly nits

samples/kernel/msg_queue/README.rst

samples/kernel/msg_queue/prj.conf

samples/kernel/msg_queue/sample.yaml

samples/kernel/msg_queue/src/main.c

samples/kernel/msg_queue/README.rst

samples/kernel/msg_queue/sample.yaml

TaiJuWu · 2025-07-17T02:49:06Z

it is a test failure, is it excepted?

The reason is described in #92865 (comment)

/**
 * @brief Put a message to a full queue for behavior test
 *
 * @details
 * - Thread A put message to a full message queue and then sleep
 * Thread B put a new message to the queue then pending on it.
 * - Thread A get all messages from message queue and check the behavior.
 *
 * @see k_msgq_put(), k_msgq_put_front()
 */
ZTEST(msgq_api_1cpu, test_msgq_pending)
{
	uint32_t rx_data;
	int pri = k_thread_priority_get(k_current_get()) - 1;
	int ret;

	k_msgq_init(&msgq1, tbuffer, MSG_SIZE, 2);
	ret = k_sem_init(&end_sema, 0, 1);
	zassert_equal(ret, 0);

	ret = IS_ENABLED(CONFIG_TEST_MSGQ_PREPEND) ?
		k_msgq_put_front(&msgq1, &data[1], K_NO_WAIT) :
		k_msgq_put(&msgq1, &data[0], K_NO_WAIT);
	zassert_equal(ret, 0);
	ret = IS_ENABLED(CONFIG_TEST_MSGQ_PREPEND) ?
		k_msgq_put(&msgq1, &data[0], K_NO_WAIT) :
		k_msgq_put_front(&msgq1, &data[1], K_NO_WAIT);
	zassert_equal(ret, 0);

	k_tid_t tid = k_thread_create(&tdata2, tstack2, STACK_SIZE,
					prepend_full_entry, &msgq1, NULL,
					NULL, pri, 0, K_NO_WAIT);

	/* that putting thread is being blocked now */
	k_sem_take(&end_sema, K_FOREVER);
	zassert_equal(tid->base.thread_state, _THREAD_PENDING);
	ret = k_msgq_get(&msgq1, &rx_data, K_FOREVER);
	zassert_equal(ret, 0);
	zassert_equal(rx_data, data[1]);

	ret = k_msgq_get(&msgq1, &rx_data, K_FOREVER);
	zassert_equal(ret, 0);
	zassert_equal(rx_data, msg3);

	ret = k_msgq_get(&msgq1, &rx_data, K_FOREVER);
	zassert_equal(ret, 0);
	zassert_equal(rx_data, data[0]);
	k_thread_abort(tid);
}

This commit introduces the k_msgq_put_front API for sending messages to a queue in a LIFO scheme. Signed-off-by: Alexander Paschoaletto <axelpinheiro@gmail.com>

this commit adds a sample code to illustrate the base usage of message queues. a producer and a consumer thread work together, exchanging messages in a FIFO (for normal payloads) and LIFO (for higher priority payloads) schemes. Signed-off-by: Alexander Paschoaletto <axelpinheiro@gmail.com>

This commit adds the tracing macros and functions related specifically to the k_msgq_put_front API. Signed-off-by: Alexander Paschoaletto <axelpinheiro@gmail.com>

sonarqubecloud · 2025-07-23T15:10:35Z

Quality Gate passed

Issues
6 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
14.4% Duplication on New Code

See analysis details on SonarQube Cloud

alexpaschoaletto · 2025-07-23T15:12:39Z

it is a test failure, is it excepted?

The reason is described in #92865 (comment)

I don't know if I understood. What exactly is to fail here?

github-actions bot added area: Samples Samples area: Kernel labels Jul 8, 2025

github-actions bot requested review from andyross, ceolin, cfriedt, dcpleung, kartben, nashif, npitre, peter-mitsis and TaiJuWu July 8, 2025 21:51

github-actions bot assigned kartben Jul 8, 2025

alexpaschoaletto changed the title ~~kernel: msgq: adding support for k_msgq_put_urgent and sample code~~ kernel: msgq: adding support for k_msgq_put_urgent and sample code Jul 8, 2025

alexpaschoaletto force-pushed the message-queue-improvements branch from d4fac33 to 85938e2 Compare July 8, 2025 22:06

kartben assigned andyross and peter-mitsis and unassigned kartben Jul 9, 2025

andyross reviewed Jul 9, 2025

View reviewed changes

TaiJuWu reviewed Jul 9, 2025

View reviewed changes

alexpaschoaletto force-pushed the message-queue-improvements branch 4 times, most recently from 34fffd8 to 66d7bfd Compare July 9, 2025 21:34

alexpaschoaletto force-pushed the message-queue-improvements branch from 66d7bfd to 347fdde Compare July 9, 2025 22:27

alexpaschoaletto requested review from andyross and TaiJuWu July 9, 2025 22:39

alexpaschoaletto force-pushed the message-queue-improvements branch 2 times, most recently from 3ca45a2 to 6ccbe34 Compare July 10, 2025 22:36

alexpaschoaletto force-pushed the message-queue-improvements branch from 5bcb4d8 to 7944b64 Compare July 15, 2025 15:21

alexpaschoaletto requested a review from TaiJuWu July 15, 2025 15:25

alexpaschoaletto force-pushed the message-queue-improvements branch from 7944b64 to 36618db Compare July 15, 2025 16:22

peter-mitsis reviewed Jul 15, 2025

View reviewed changes

alexpaschoaletto force-pushed the message-queue-improvements branch from 36618db to fcd6407 Compare July 15, 2025 18:20

github-actions bot added the area: Tracing Tracing label Jul 15, 2025

github-actions bot requested a review from teburd July 15, 2025 18:59

alexpaschoaletto force-pushed the message-queue-improvements branch from 1dc7e6e to 3b88b4a Compare July 15, 2025 19:02

TaiJuWu reviewed Jul 16, 2025

View reviewed changes

alexpaschoaletto force-pushed the message-queue-improvements branch 2 times, most recently from 68bfba2 to 8223338 Compare July 16, 2025 18:24

andyross previously approved these changes Jul 16, 2025

View reviewed changes

peter-mitsis previously approved these changes Jul 16, 2025

View reviewed changes

JarmouniA reviewed Jul 16, 2025

View reviewed changes

JarmouniA added the DNM This PR should not be merged (Do Not Merge) label Jul 19, 2025

alexpaschoaletto dismissed stale reviews from peter-mitsis and andyross via 985db90 July 23, 2025 14:31

alexpaschoaletto force-pushed the message-queue-improvements branch from 8223338 to 985db90 Compare July 23, 2025 14:31

alexpaschoaletto added 3 commits July 23, 2025 11:41

kernel: msgq: adding support to k_msgq_put_front

432d9d7

This commit introduces the k_msgq_put_front API for sending messages to a queue in a LIFO scheme. Signed-off-by: Alexander Paschoaletto <axelpinheiro@gmail.com>

tracing: msgq: adding dedicated tracing for k_msgq_put_front

3a60725

This commit adds the tracing macros and functions related specifically to the k_msgq_put_front API. Signed-off-by: Alexander Paschoaletto <axelpinheiro@gmail.com>

alexpaschoaletto force-pushed the message-queue-improvements branch from 985db90 to 3a60725 Compare July 23, 2025 14:42

JarmouniA removed the DNM This PR should not be merged (Do Not Merge) label Jul 23, 2025

JarmouniA approved these changes Jul 23, 2025

View reviewed changes

kernel: msgq: adding support for k_msgq_put_front and sample code #92865

Are you sure you want to change the base?

kernel: msgq: adding support for k_msgq_put_front and sample code #92865

Conversation

alexpaschoaletto commented Jul 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andyross left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexpaschoaletto Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TaiJuWu left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TaiJuWu Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alexpaschoaletto Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TaiJuWu Jul 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

alexpaschoaletto commented Jul 9, 2025

Uh oh!

TaiJuWu commented Jul 10, 2025

Uh oh!

peter-mitsis commented Jul 15, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TaiJuWu commented Jul 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

peter-mitsis commented Jul 16, 2025

Uh oh!

JarmouniA left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kernel: msgq: adding support for `k_msgq_put_front` and sample code #92865

kernel: msgq: adding support for `k_msgq_put_front` and sample code #92865

alexpaschoaletto commented Jul 8, 2025 •

edited

Loading

alexpaschoaletto Jul 9, 2025 •

edited

Loading

TaiJuWu left a comment •

edited

Loading

TaiJuWu Jul 9, 2025 •

edited

Loading

alexpaschoaletto Jul 9, 2025 •

edited

Loading

TaiJuWu Jul 10, 2025 •

edited

Loading

TaiJuWu commented Jul 15, 2025 •

edited

Loading

TaiJuWu commented Jul 17, 2025 •

edited

Loading